Skip to main content

Technical Use Guide

VersionModified ByApproverDateChanges made
V1.0Codey FunstonCodey Funston01/01/2025Document Creation

Support​

Have a question or issue you would like help with in Azure DevOps? Contact support.
* Support queries will be available in semester 1 of 2025 only.

Introduction​

Azure DevOps (ADO) gives you a lot of technical control through GUI-based configuration and a highly documented API. During this semester (T3 2024) we trialed key technical features for a single team in a project, the SecDevOps team. The following was trialed:

  1. User Dashboards
  2. GitHub Connections
  3. API Calls through GitHub Actions
  4. Basic Queries

The following documentation gives a brief overview of those areas. The main guide is a video playlist available here:

Creating Custom User Dashboards​

Below is how the dashboard that we tested turned out. It was designed to fit nicely on devices with screens as small as 13"/14". It is structured to show the most important information first, and quickly. With the elements not visible until scrolling having less importance, and not being key information sources for project insight.

Dashboard at Login​

no-scroll-dashboard-view

Dashboard After Page Scroll​

no-scroll-dashboard-view

The widgets on screen are a mix of pre-built ones by Microsoft, such as the work assigned at the top left, and markdown pages such as the task creation templates one below. A burnup chart was chosen for showing progress against project scope as it is better for reducing stress in a team with its focus on progress instead of work to do. If you look at the top right of the screen in the dashboard at login you will se three blocks with colours indicating their state. These colours can be customised by editing the widgets and adding your own "levels of severity". Note that there is a default colour and that the rules have precedence based on their order from top to bottom.

no-scroll-dashboard-view

Pull Request View​

An important part of the dashboard for the DevSecOps (the team that the trial was for) is the pull requests (PR's) view. It is built on a custom query that selects tasks in the current semester that are in the PR's area path. These tasks are automatically created through GitHub actions which is mostly covered in the video walkthrough. The goal of creating the automation and view in the dashboard was to join code reviews and project management into one thing. It means that team leaders can automatically assigned PR's to team members based on repository preferences, then manage their completion. And, team members can ensure that they don't forgot to review any PR's as they are part of their main project management suite.

Pull Request Dashboard View​

no-scroll-dashboard-view

Connecting to GitHub​

Setting up a reference to GitHub is relatively straightforward. To do so follow these steps:

In GitHub​

  1. Go to the repository that you want to connect.

  2. Ask your team leader to add you as a "direct access" member. For team leaders, access this through Repository Settings >> Collaborators and teams >> Manage access >> Direct access.

  3. Now you need to generate a personal access token (PAT) through your user account settings. Go to Settings >> Developer Settings >> Personal access tokens >> Tokens (classic) >> Generate new token.

  4. Make sure that the token has the following, and only the following, permissions:

    1. repo
    2. admin:repo_hook
    3. read:user
    4. user:email

In ADO​

  1. Go to Project Settings >> Boards >> GitHub connections.
  2. Click "New connection"
  3. Either paste your PAT or import it from a secure password manager.
  4. Click Connect.

This will allow you to create new branches for tasks, or link tasks to existing commits, PR's, or branches. Note that this is not related to the "Repos" service in ADO as this can only copy the GitHub repo and then host it separately. As of writing this (January 2025) we are not planning on using this tool for repository hosting.

API Calls and Github Actions​

The documentation for the part of the API that we tested is hosted by Postman here. We don't go into the API very much aside from that website and a bit in the video walkthrough. It is better to go to Microsoft's official documentation as it is a large API and any small syntax or logic errors can result in a lot of troubleshooting (from experience). Therefore, you should go to the source.

Use of Custom Queries​

Azure DevOps gives you an easy to use query editor. As pictured below you add fields to check for, a logical operator for comparison, and the value. It is good practice to have the following clause in all queries so that anything in the current semester is returned. More detail is included in the video demonstration.

Changed Date > @Today - 100

Query To Select PR's​

no-scroll-dashboard-view